Network Support Library/RoseWare - Network Support Library.iso/apidev/tpapi.exe/DOCS/OVERVIEW.DOC

Text File | 1994-01-14 | 8KB | 200 lines

              *************************************************
              * Turbo Pascal API's for Novell Netware (TPAPI) *
              *************************************************

      TPAPI (c) Copyr. 1991 - 1994 Antonio Covelli ALL RIGHTS RESERVED


OVERVIEW
--------

TPAPI (pronounced Tee-Pap-E) is an object oriented library of Netware API's
written in Borland's PASCAL language. Novell has always shunned the installed
base of PASCAL engineers when providing their SDK's and TPAPI is designed to
address this shortsight. With TPAPI there is no need to "shell out" to do tasks
such as logging in or out, spooling to a print queue, mapping drives or
obtaining specific Netware information.

Currently TPAPI consists of over 21,000 lines of PASCAL and built-in assembler.
Due to the use of BASM TPAPI requires Turbo Pascal 6.x or later. Further
information detailing the necessary requirements can be found in the section
titled TPAPI REQUIREMENTS.

Support is provided for Novell Netware v2.x, Netware v3.x and Netware v4.x.
Many of the new v3.x and v4.x API's have not been implemented but will be done
at a later stage.  IPX/SPX support is also to be implemented.

With the advent of Netware v4.x Novell released new client shells called the
Virtual Loadable Module client (VLM). This client shell is quite different from
the older NETX shell in two ways :

    1) It is actually a requester. DOS decides whether the called API is for
       DOS or the Netware requester.
    2) When executing API's you call the requester directly and not by executing
       INT 21h as in NETX.

TPAPI is being changed to support the VLM client and can automatically detect
whether the VLM or NETX client is in use and act accordingly. Novell has stated
that virtually all research and development is being carried out on making the
VLM client successful. This basically means that the NETX client, like the
IPX.OBJ, is a dying breed.

Novell has also started publish to the NCP (Netware Core Protocol) transport
mechanism for all their API's. NCP allows "raw" packets to be sent to a file
server. When a file server receives an NCP packet it will attempt to interpret
the contents and act in one of the following ways :

    1) if the packet is invalid issue an Invalid Packet error.
    2) if the packet is correct but contains incorrect parameters ABEND.
    3) execute the request and send either/or return packets or result codes.

Many of the NCP equivalent API's have been incorporated into TPAPI but Novell
has not published all the information as of yet. The major benefit of using NCP
is that the request/receive packet structures are identical regardless of what
client software is running.


DESIGN OF TPAPI
---------------

TPAPI is an Object Oriented (OOP) library which enables anyone to extend the
library and tailor it for their own needs. One thing that you must not do is
to directly manipulate any of the internal variables but use the methods
provided.

When adding your own methods to the library please follow theses guidelines :

function MyObj.ChangePW (ObjectName : TObjectName;
                         ObjectType : OT_BinderyType;
                         OldPW, NewPW : TPassword) : word;

begin

  InitStandardBuffers;
  {The above method initialises the request/reply buffers and will reallocate
   them if DynamicAllocation is true. It also sets the buffer offset to 2.}

  ObjectName := UppercaseNW (ObjectName);
  OldPW := UppercaseNW (OldPW);
  NewPW := UppercaseNW (NewPW);
  {When dealing with the bindery Netware likes all strings to be in uppercase}

  AddByte (64);
  {Add the subfunction code at offset 2. Addbyte thens increments the offset
   by 1.}

  AddWordSwap (ObjectType);
  {Add the ObjectType swapped and increment the offset by 2.}

  AddString (ObjectName, 0);
  {Add the string contained in ObjectName, starting at pos 0 of the string, and
   increment offset by length of ObjectName.}

  AddString (OldPassword, 0);
  AddString (NewPassword, 0);
  {See the comment for AddString (ObjectName, 0).}

  AddTotal (Request, True);
  {Add the total length of the request buffer into position 0. Due to this
   being an NCP call the length needs to be swapped. If this call was not an
   NCP call then pass false.}

  SetTotal (Receive, 0);
  {Sets the total of the receive buffer expected back. The second parameter is
   the size of the buffer to be returned.}

  ChangePW := NCPRequest ($17, GetTotal (Request), nwRequestBuffer.RealPtr,
                          GetTotal (Receive), nwReceiveBuffer.RealPtr);
  {Calls the function NCPRequest which prepares the buffers for passing to the
   Netware shell. The first parameter is the main function code, the second is
   the size of the request buffer, the third the actual request buffer pointer,
   followed by the size of the receive buffer and its pointer.}

end; {MyOBJ.ChangePW}


TPAPI REQUIREMENTS
------------------

TPAPI requires one or more of the following PASCAL compilers



  TARGET PLATFORM            COMPILER NEEDED


  DOS (Real Mode)            Turbo Pascal 6.x
                             Turbo Pascal 7.x
                             Borland Pascal 7.x

  DOS (Protected Mode)       Borland Pascal 7.x

  WINDOWS                    Borland Pascal 7.x
                             Turbo Pascal for Windows v1.x

In addition (for testing purposes) you should have the client software installed
and connected to a file server running a copy of Netware.

TPAPI HAS NOT BEEN TESTED WITH OTHER MANUFACTURERS PASCAL COMPILERS AND CANNOT
BE GUARANTEED TO FUNCTION OR COMPILE CORRECTLY.




CONTACTING THE AUTHOR
---------------------

I can be contacted in a number of ways for technical support or just plain
chat.

The easiest method is via email :

    CIS            100015,3611
    CIX            tcovelli
    Internet       [e-mail]

or via postal mail at

   104 Brookfield Road,
   Aldershot,
   Hampshire.
   GU12 4UT
   United Kingdom


ABOUT THE AUTHOR
----------------

I originally became involved in Novell Netware in 1987 when I was thrown in at
the deep end by the Company I was working for. The LAN consisted of
approximately 15 file servers (which consisted of Novell 286b, Televideo PM16
and Televideo PM286) running Televideo Netware and Netware 286 v2.0a.

Soon the network grew and the machines were replaced with Compaq Deskpro 386/25
with 16mb RAM and 4x300 ESDI drives. After a while the LAN peaked to 30 file
servers with 600 concurrent users (running a mortgage book of over 3.5b pounds).

The site was based in Fleet within two buildings which were linked by a fibre
link, running over thin ethernet. As you can imagine running a network of that
size took a considerable amount of time so TPAPI was developed.

In 1992 I left and joined a large insurance company based near London and am
the Senior PC/LAN analyst. The network is slowly growing and will become one
of the most advanced in Britain in time.

I spend a great deal of time relaxing by listening to music, trying to succeed
in RPG games (on the computer) and playing with my son (who is rapidly showing
an interest in computers although he is only 2.5 years old).


TRADEMARKS AND COPYRIGHTS
-------------------------

  TPAPI is a trademark of Antonio Covelli. ALL RIGHTS RESERVED.

  Turbo/Borland Pascal is a registered trademark of Borland International.

  Netware is a registered trademark of Novell, Inc.

  LHA is copyright Yoshi.